package com.compunit.composite.core.interfaces.xml;

/**
 * <code>IXMLTag</code> defines the interface of a
 * hierarchical element in the XML structure. It has
 * a unique name, a list of children <code>ITag</code>,
 * a set of key and value pairs. 
 *
 * @author Yi Wang (Neakor)
 * @version Creation date: 11-06-2009 18:17 EST
 * @version Modified date: 11-06-2009 18:23 EST
 */
public interface IXMLTag {

	/**
	 * Retrieve the key-value pair keys maintains in
	 * this tag.
	 * @return The <code>Iterable</code> of all the
	 * <code>String</code> keys.
	 */
	public Iterable<String> getKeys();
	
	/**
	 * Retrieve the name of this tag.
	 * @return The <code>String</code> name.
	 */
	public String getName();
	
	/**
	 * Retrieve the parent XML tag.
	 * @return The parent <code>IXMLTag</code>. If this
	 * tag the root tag, <code>null</code> is returned.
	 */
	public IXMLTag getParent();

	/**
	 * Retrieve the children tags of this tag.
	 * @return The <code>Iterable</code> of all the
	 * children <code>IXMLTag</code>.
	 */
	public Iterable<IXMLTag> getChildren();
	
	/**
	 * Retrieve the value in this tag with the given
	 * key.
	 * @param key The <code>String</code> key.
	 * @return The <code>String</code> value.
	 */
	public String getValue(final String key);
	
	/**
	 * Convert the current information into the external
	 * XML file format.
	 * @return The XML file formatted <code>String</code>
	 * representation of this tag and its children.
	 */
	public String toExternal();
}
